Some aspects of the Keyfactor API
An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. request and response formats are consistent across all endpoints. This includes a small set of HTTP headers, HTTP statuses returned by the server for successful requests, and various error conditions. Common request headers are given in Table 145: Common Request Headers, common response headers (for successful requests and certain unsuccessful requests) are given in Table 146: Common Response Headers, and HTTP statuses are given in Table 147: HTTP Statuses.
By default, all Keyfactor API methods start with a base path, which corresponds to an application under IIS; this path is configurable at install time. The default base path is KeyfactorApi. The API component name and method name then comprise the parts of the URL, each separated by a forward slash. For example, /KeyfactorApi/Certificates/Import would be the URL format for the Import method of the Certificates component.
Table 145: Common Request Headers
|
Header Name |
Header Value |
Description |
|---|---|---|
|
Content-Type |
application/json OR application/xml |
POST methods use application/json. When application/xml is needed, it is specifically indicated on the endpoint page. |
|
Accept |
application/json; charset=utf-8 |
Most methods returning complex values will use this content type. |
|
Authorization |
Basic <base-64 DOMAIN\user:pass> OR Bearer <OAuth 2.0 token> |
For more information about authenticating to the Keyfactor API, see Authenticating to the Keyfactor API. |
|
Host |
<Keyfactor Command server hostname> |
Address of Keyfactor Command server. Automatically generated in most clients. |
|
Content-Length |
Request length in bytes |
Optional, but automatically generated by most clients. |
|
X-Keyfactor-Requested-With |
XMLHttpRequest |
This is mandatory to send in a request to the Keyfactor API on POSTs, PUTs, and DELETEs, and the value is case sensitive. This is for security. |
| X-Keyfactor-API-Version | 1 or 2 | Desired version of the endpoint. If not provided, this defaults to version 1. |
Table 146: Common Response Headers
|
Header Name |
Header Value |
Description |
|---|---|---|
| api-supported-versions | 1.0, 2 | The supported endpoint versions for the Keyfactor API. |
|
Cache-Control |
no-cache |
API requests are generally not cacheable. Note that this is not respected by all client systems. |
|
Content-Length |
<varies> |
Length of the HTTP response. |
|
Content-Type |
application/json |
Most calls return application/json, but occasionally text/plain or text/xml. |
|
Date |
<varies> |
Timestamp of the HTTP response. |
|
Expires |
-1 |
Usually ignored. |
|
Pragma |
no-cache |
API requests are generally not cacheable. Note that this is not respected by all client systems. |
|
Server |
<varies> |
Software version reported by IIS platform hosting Keyfactor Command. |
| Strict-Transport-Security | max-age=31536000; includeSubDomains | When Keyfactor Command is configured with HTTP Strict Transport Security (HSTS) as per Keyfactor recommended configuration |
|
X-AspNet-Version |
<varies> |
Version of ASP.NET supporting Keyfactor Command installation. |
| X-Keyfactor-Correlation-Id | <varies> | GUID indicating the correlation ID of the request. This is used to help identify log messages that originate from the request. |
| X-Keyfactor-Product-Version | <varies> | Keyfactor Command platform version. |
|
X-Powered-By |
ASP.NET |
Header added by underlying ASP.NET implementation. |
|
X-Total-Count |
<varies> |
Total number of elements returned. |
|
Number/Name |
Description |
|---|---|
|
200 OK |
Request successful; results in response body |
|
204 No Content |
Request successful; no content in response body |
|
400 Bad Request |
Malformed or invalid data; additional information may be available in the response body and/or Keyfactor Command server logs |
|
401 Unauthorized |
Invalid credentials (user unauthenticated) |
|
403 Forbidden |
Can often indicate that the credentials map to a user without permissions for this action in Keyfactor Command (user unauthorized) |
|
404 Page not Found |
Invalid request path |
|
500 Internal Server Error |
Keyfactor Command encountered an unexpected error attempting to handle the request. See response body and Keyfactor Command server logs for details. |
|
502 Bad Gateway |
Keyfactor Command attempted to contact a CA or other upstream server to process the request, but was unable to. See Keyfactor Command server logs for details. |
Was this page helpful? Provide Feedback